The FacClient object contains the following methods:
The AddFacilityRecord method adds a new facility from an XML record.
AddFacilityRecord(RecordXML as String)
| Parameter | Required | Description |
|---|---|---|
|
RecordXML |
Yes |
The XML record that contains the attributes that will be stored in the new facility. |
The XML used to create the facility should be in the same format as the XML returned from ReadFacilityRecord, as in the following example.
|
<CygNetFacilityRecord lock_user="VSI\" lock_time="-1214347123" facility_attr0="" facility_attr1="" facility_category="REMDEV" facility_desc="CYGDEMO_RTU" facility_id="Cyg_RTU" facility_info0="" facility_info1="" facility_is_active="Y" facility_is_ref_any="Y" ... /> |
Example
The following example creates a new facility using an XML record stored in edtXML.
|
Sub AddRecord() FacClient.AddFacilityRecord edtXML.Text MsgBox "Facility Added" End Sub |
The Connect method connects the object to a service.
Connect(DomainSiteService As String)
| Parameter | Required | Description |
|---|---|---|
|
DomainSiteService |
Yes |
The [Domain]Site.Service to which to connect. A domain is optional. The service must be a valid FAC. |
Returns 0 if successful and a non-zero value if the connection failed.
Example
The following example connects the FacClient object to the CYGDEMO.FAC on domain 5410:
|
Sub FacConnect() 'Connect to a FAC Dim FacClient Set FacClient = CreateObject("CxFac.FacClient") FacClient.Connect("[5410]CYGDEMO.FAC") End Sub |
The DeleteFacilityRecord method deletes a facility.
DeleteFacilityRecord(FacTag as String) As Boolean
| Parameter | Required | Description |
|---|---|---|
|
FacTag |
Yes |
The facility to delete. |
Example
The following example deletes a facility and notifies the user if an error occurs.
|
Sub DeleteFacRecord() Dim Success
Success = FacClient.DeleteFacilityRecord ("CYGDEMO.UIS::CYG_METER")
If Success = True Then MsgBox "Facility deleted" Else MsgBox "Error in deleting" End IF End Sub |
The Disconnect method disconnects from the service.
Disconnect() As Short
Example
The following example disconnects from the connected FAC service.
|
Sub FacDisconnect() FacClient.Disconnect() MsgBox "Disconnected from FAC" End Sub |
The FinishBulkUpdates method disables bulk updating.
FinishBulkUpdates()
This method disables bulk updating and makes the FAC flush changes to the disk after every point is updated.
Example
The following example stops bulk updating and restores normal updating.
|
Sub StopBulkUpdates() FacClient.FinishBulkUpdates MsgBox "Bulk Updating disabled" End Sub |
The GetActiveServices method returns a list of active FAC services.
GetActiveServices(ServiceList as Array)
| Parameter | Required | Description |
|---|---|---|
|
ServiceList |
Yes |
The list of IDs of active facilities returned by this method. |
Example
The following example retrieves a list of active FAC services and stores them in a list box.
|
Sub GetActiveServices() Dim activeServices Dim fac
FacClient.GetActiveServices activeServices
For Each fac In activeServices lboFac.AddString(fac) Next End Sub |
The GetConsoleData method returns the console text and display attributes as two 25x80 arrays of unsigned characters.
GetConsoleData(ByRef pText, ByRef pAttr) As Integer
| Parameter | Required | Description |
|---|---|---|
|
pText |
Yes |
A two-dimensional 25x80 array of console text attributes returned by this method. |
|
pAttr |
Yes |
A two-dimensional 25x80 array of console display attributes returned by this method. |
This method returns 0 if successful.
Example
The following example writes the console text and display attributes to a CSV file.
|
Sub Dim aryText, aryAttr, nRet nRet = FacClient.GetConsoleData(aryText, aryAttr)
' Write text attributes to CSV file Dim i, j, strMsg For i = 0 To UBound(aryText, 1) For j = 0 To UBound(aryText, 2) strMsg = strMsg + CStr(aryText(i, j)) + "," Next strMsg = strMsg + vbCr Next
dim fso, file Set fso = CreateObject("Scripting.FileSystemObject") Set file = fso.OpenTextFile("c:\console_text_attrs.csv", 2, True) file.WriteLine(strMsg) file.Close
strMsg = ""
' Write display attributes to CSV file For i = 0 To UBound(aryAttr, 1) For j = 0 To UBound(aryAttr, 2) strMsg = strMsg + CStr(aryAttr(i, j)) + "," Next strMsg = strMsg + vbCr Next
Set file = fso.OpenTextFile("c:\console_disp_attrs.csv", 2, True) file.WriteLine(strMsg) file.Close
MsgBox nRet End Sub |
The GetCvsOnlyFacilities method returns a list of current value service facilities.
GetCvsOnlyFacilites(SiteService as String, FacilityList as Array)
| Parameter | Required | Description |
|---|---|---|
|
SiteService |
Yes |
The Site.Service to which the facilities are connected. This parameter must specify a current value service. |
|
FacilityList |
Yes |
The list of facilities returned by this method. |
The returned list will not include facilities associated with the DDS, such as remote device or communication device facilities.
Example
The following example retrieves all facilities associated with CYGDEMO.UIS and displays them in a list box.
|
Sub GetCvsFacs() Dim CvsList Dim fac
FacClient.GetCvsOnlyFacilities "CYGDEMO.UIS", CvsList
For Each fac In CvsList lboFac.AddString(fac) Next End Sub |
The GetCvsServiceList method returns the service names of all current value services referenced by facility records.
GetCvsServiceList(ServiceList as Array)
| Parameter | Required | Description |
|---|---|---|
|
ServiceList |
Yes |
The list of current value services returned by this method. |
The returned service names will be in Site.Service format.
Example
The following example gets all the current value services that the facilities are associated with and stores them in a list box.
|
Sub GetCvsServices() Dim CvsList Dim cvs
'Get a list of CVSes associated with the PNT service FacClient.GetCvsServiceList CvsList
'Store each CVS in a list box For Each cvs In CvsList lboCvs.AddString(cvs) Next End Sub |
The GetDeviceCatSpecificFacilities method returns the list of facilities with a specified device category type.
GetDeviceCatSpecificFacilities(SiteService as String, DeviceCategory as String, FacilityList as Array)
| Parameter | Required | Description |
|---|---|---|
|
SiteService |
Yes |
The Site.Service with which the facilities are associated. This parameter must specify a current value service. |
|
DeviceCategory |
Yes |
The device category of the device. Valid device category options are:
|
|
FacilityList |
Yes |
The list of facilities returned by this method. |
Example
The following example retrieves all facilities with a device category of RD, and displays them in a list box.
|
Sub GetDeviceCatFacs() Dim FacList Dim fac
FacClient.GetDeviceCatSpecificFacilities "CYGDEMO.UIS", "RD", FacList
For Each fac In FacList lboFac.AddString(fac) Next End Sub |
The GetEmptyRecordXml method returns an empty facility record XML.
GetEmptyRecordXml() As String
This method can be used in the process of creating a new facility. After the empty record XML is retrieved, use the SetRecordXMLAttribute method to set the new facilty record attribute values. Then use the AddFacilityRecord method to add the new facility from the XML string created by the SetRecordXMLAttribute method.
The string is returned as XML. The following is an example of what this method will return.
|
<CygNetFacilityRecord /> |
Example
The following example gets the XML for an empty facility and saves it to an XML document.
|
Sub GetEmptyRecord() 'Get facility xml Dim strInfo strInfo = FacClient.GetEmptyRecordXml
'Save XML Set xmlDoc = CreateObject("Msxml2.DOMDocument") xmlDoc.loadXML(strInfo) xmlDoc.save("C:\EmptyFacility.xml") End Sub |
The GetFacilitiesByFacilityType method returns the list of facilities of a specified facility type.
GetFacilitiesByFacilityType(FacilityType as String, SiteService as String, FacilityList as Array)
| Parameter | Required | Description |
|---|---|---|
|
FacilityType |
Yes |
The facility type of the facilities to be retrieved. |
|
SiteService |
Yes |
The Site.Service of the current value service with which the facilities are associated. |
|
FacilityList |
Yes |
The list of facilities returned by this method. |
Example
The following example retrieves all facilities with a facility type of "REMDEV" and displays them in a list box.
|
Sub GetByFacilityType() Dim FacList Dim fac
FacClient.GetFacilitiesByFacilityType "REMDEV", "CYGDEMO.UIS", FacList
For Each fac In FacList lboFac.AddString(fac) Next End Sub |
The GetFacilitiesList method returns the list of the facilities associated with a given Site.Service.
GetFacilitiesList(SiteService as String, FacilityList as Array)
| Parameter | Required | Description |
|---|---|---|
|
SiteService |
Yes |
The Site.Service of the current value service with which the facilities are associated. |
|
FacilityList |
Yes |
The list of facilities returned by this method. |
The returned list of facilities will be stored and sorted in alphabetical order by facility tag.
Example
The following example retrieves all facilities associated with CYGDEMO.UIS and displays them in a list box.
|
Sub GetFacilitiesList() Dim FacList Dim facility
FacClient.GetFacilitiesList "CYGDEMO.UIS", FacList
For Each facility In FacList lboFac.AddString(fac) Next End Sub |
The GetFacilityAttributeList method returns the list of attribute names that can be stored in a facility.
GetFacilityAttributeList(FacilityList as Array)
| Parameter | Required | Description | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
FacilityList |
Yes |
Output. The returned two-dimensional array of service definitions. The array order is defined as follows:
|
Example
The following example retrieves a list of attribute names and displays them in a list box.
|
Sub GetFacAttributes() Dim FacList Dim fac
FacClient.GetFacilityAttributeList FacList
For Each fac In FacList lboFac.AddString(fac) Next End Sub |
The GetFacilityTypeList method returns the list of facility types for the given FAC service.
GetFacilityTypeList(SiteService as String, FacilityTypeList As Variant)
| Parameter | Required | Description |
|---|---|---|
|
SiteService |
Yes |
The Site.Service for which to retrieve a list of facility types. If this parameter is an empty string, all facility types will be returned. |
|
FacilityTypeList |
Yes |
The list of facility types returned by this method. |
Example
The following example displays the list of all facility types.
|
Sub Dim aryFacTypes FacClient.GetFacilityTypeList "", aryFacTypes
Dim i, strMsg For i = 0 To UBound(aryFacTypes) strMsg = strMsg + aryFacTypes(i) + vbCr Next
MsgBox strMsg End Sub |
The GetRecordXMLAttribute method returns the value of an attribute from a facility record.
GetRecordXMLAttribute(RecordXML as String, RecordAttribute as String) As String
| Parameter | Required | Description |
|---|---|---|
|
RecordXML |
Yes |
The XML record from which to retrieve the attibute value. |
|
RecordAttribute |
Yes |
The name of the attribute for which to retrieve a value. If this attribute is not present in RecordXML, this method will return an empty string. |
Example
The following example gets the value for the attribute facility_id and displays it in a message box.
|
Sub GetRecordAttribute() edtMessageBox.Test = FacClient.GetRecordXMLAttribute( _ edtXML.Text, "facility_id") End Sub |
The GetReferences method refreshes the list of services referenced by the connected service.
GetReferences() As Short
Example
The following example refreshes the list of referenced services.
|
Sub GetReferences() FacClient.GetReferences() End Sub |
The ReadFacilityRecord method returns the XML record for a facility.
ReadFacilityRecord(FacTag as String) As String
| Parameter | Required | Description |
|---|---|---|
|
FacTag |
Yes |
The tag of the facility for which to retrieve a record. |
The record will be returned in XML format. The following is an example of an excerpt of the returned XML.
|
<CygNetFacilityRecord lock_user="VSI\" lock_time="-1214347123" facility_attr0="" facility_attr1="" facility_category="REMDEV" facility_desc="CYGDEMO_RTU" facility_id="Cyg_RTU" facility_info0="" facility_info1="" facility_is_active="Y" facility_is_ref_any="Y" ... /> |
Example
The following example retrieves a facility record and saves it to an XML file.
|
Sub ReadFacRecord() 'Get facility xml Dim Record Record = FacClient.ReadFacilityRecord("CYGDEMO.UIS::Cyg_RTU")
'Save XML Set xmlDoc = CreateObject("Msxml2.DOMDocument") xmlDoc.loadXML(Record) xmlDoc.save("C:\FacilityRecord.xml") End Sub |
The ReadFacilityRecordForUpdate method returns a facility record and locks the facility for updates.
ReadFacilityRecordForUpdate(FacTag as String) As String
| Parameter | Required | Description |
|---|---|---|
|
FacTag |
Yes |
The tag of the facility to read for updates. |
The ReadFacilityRecordForUpdate method returns a record for the given facility and locks the record for update. When the record is locked for update, other users are prevented from editing it until the lock is released or times out. Follow this method by a call to UpdateFacilityRecord or ReleaseFacilityRecordLock.
Example
The following example displays a facility record in edtXML and locks the facility for updates.
|
Sub ReadFacRecordForUpdate() edtXML.Text = FacClient.ReadFacilityRecordForUpdate(Tag) MsgBox "Facility locked" End Sub |
The ReadFacilityRecords method returns an XML string containing records for each of the given facility tags.
ReadFacilityRecords(ArrFacTags as Variant) As String
| Parameter | Required | Description |
|---|---|---|
|
ArrFacTags |
Yes |
A list of facility tags for which to retrieve records. |
The records will be returned in XML format. The following is an example of an excerpt of the returned XML.
|
<CygNetFacilityRecords> <CygNetFacilityRecord lock_user="FAC" lock_time="-1298593501" facility_attr0="" facility_attr1="" facility_attr10="" facility_attr11="" facility_attr12="" facility_attr13="" facility_attr14="" facility_attr15="" facility_attr16="" facility_attr17="" .../> ... </CygNetFacilityRecords> |
Example
The following example writes facility records to an XML file.
|
Sub Dim aryFacTags ReDim aryFacTags(2)
aryFacTags(0) = "CYGDEMO.UIS::20090303" aryFacTags(1) = "CYGDEMO.UIS::FLOWAUTOAP15" aryFacTags(2) = "CYGDEMO.UIS::FLOWAUTOAP15A"
Dim strXml strXml = FacClient.ReadFacilityRecords(aryFacTags)
'Save XML Dim xmlDoc Set xmlDoc = CreateObject("Msxml2.DOMDocument") xmlDoc.loadXML(strXml) xmlDoc.save("C:\FacilityRecords.xml") End Sub |
The ReleaseFacilityRecordLock method unlocks a facility record to allow editing.
ReleaseFacilityRecordLock(FacTag as String, RecordXML as String)
| Parameter | Required | Description |
|---|---|---|
|
FacTag |
Yes |
The tag of the facility to unlock. Use the format SITE.SERVICE::FACILITYID |
|
RecordXML |
Yes |
The XML record of the facility to unlock. Generated by ReadFacilityRecord. |
This method releases the lock on the facility record created by the ReadFacilityRecordForUpdate method. Once the lock on the record is released, it can then be edited by other users.
Example
The following example unlocks the CYGDEMO_RTU facility record.
|
Sub ReleaseFacLock() FacClient.ReleaseFacilityRecordLock Tag, XML MsgBox "Facility unlocked" End Sub |
The SetRecordXMLAttribute method sets an attribute value of a specified facility record.
SetRecordXMLAttribute(RecordXML as String, RecordAttribute as String, AttributeValue as String) As String
| Parameter | Required | Description |
|---|---|---|
|
RecordXML |
Yes |
The facility record XML for which to set an attribute. Generated by ReadFacilityRecord. |
|
RecordAttribute |
Yes |
The attribute for which to set a value. |
|
AttributeValue |
Yes |
The new value of the attribute. |
This method creates a new XML string containing updated facility attribute values to be used by either the UpdateFacilityRecords method for a single facility record or the UpdateAttributesForFacilities method for updating multiple facility records.
SetRecordXmlAttribute sets the attribute name to lowercase before modifying the XML.
Example
The following example creates a new XML string with the new facility record attribute value, but doesn’t update the facility itself.
|
Sub SetRecordAtt() Dim newPoint
newPoint = FacClient.SetRecordXMLAttribute (XML, "facility_category" _ "REMDEV") edtMessageBox.Text = newPoint End Sub |
The StartBulkUpdates method enables faster updating.
StartBulkUpdates()
Normally, the FAC service will flush the changes to the disk after each facility is updated. If Bulk Updating is enabled, it will only flush every thirty seconds. This decreases the update time but increases the likelihood that data will be lost if a bad shutdown occurs. CygNet recommends that this feature only be turned on while bulk updating occurs and then turned off when finished, using FinishBulkUpdates.
Example
The following example enables Bulk Updating.
|
Sub StartBulkUpdates() FacClient.StartBulkUpdates() MsgBox "FAC Client has started bulk updating" End Sub |
The UpdateAttributesForFacilities method updates multiple facility records with new attribute values from an XML string.
UpdateAttributeForFacilities(FacTags as Array, RecordXML as String, errors as Array) As Integer
| Parameter | Required | Description |
|---|---|---|
|
FacTags |
Yes |
The array of tags of facilities to be updated |
|
RecordXML |
Yes |
The XML string that contains the new facility attribute values. |
|
errors |
Yes |
A list of errors returned by this method. |
This method updates multiple facility records using the XML string returned by the SetRecordXMLAttribute method.
For the RecordXML used in this method, do not include an entire facility record since the method updates multiple facility records. The update would fail as a result of trying to create multiple instances of an identical facility record. The XML string should only contain the attributes that you want to be set the same on all the facilities that are to be updated. The attributes that are not included in the XML string will not be updated when the method is called.
For example, if the following is stored in RecordXML, only Facility Attribute 0 will be updated:
|
<CygNetFacilityRecord facility_attr0="Bill" /> |
Example
The following example updates an array of facilities with the attributes from edtXML, and outputs a list of errors in lboerrors.
|
Sub UpdateAttributes() Dim Tags(1) Dim errors(1) Dim err
Tags(0) = "CYGDEMO.UIS::CYG_RTU" Tags(1) = "CYGDEMO.UIS::CYG_METER"
FacClient.UpdateAttributesForFacilities Tags, edtXML.Text, errors
For Each err In errors lboerrors.AddString(err) Next MsgBox "Facilities updated" End Sub |
The UpdateFacilityRecord method updates a single facility record from an XML string.
UpdateFacilityRecord(FacTag as String, RecordXML as String)
| Parameter | Required | Description |
|---|---|---|
|
FacTag |
Yes |
The tag of the facility to update. |
|
RecordXML |
Yes |
The XML string containing the new facility attribute values. |
This method updates a single facility record using the XML string returned by the SetRecordXMLAttribute method.
RecordXML does not need to contain an entire facility record. If an attribute is left out, it will not be updated when this method is called. For example, if the following is stored in RecordXML, only Facility Attribute 0 will be updated:
|
<CygNetFacilityRecord facility_attr0="Bill" /> |
Example
The following example updates a facility record with the modified XML stored in edtXML.
|
Sub UpdateFacRecord() FacClient.UpdateFacilityRecord Tag, edtXML.Text MsgBox "Facility Updated" End Sub |
|
|
|
